<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
    <head>
        <!-- Book generated using mdBook -->
        <meta charset="UTF-8">
        <title>Hello Terminal - Bracket-Lib Usage Guide</title>
        
        


        <!-- Custom HTML head -->
        


        <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
        <meta name="description" content="">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <meta name="theme-color" content="#ffffff" />

        
        <link rel="icon" href="favicon.svg">
        
        
        <link rel="shortcut icon" href="favicon.png">
        
        <link rel="stylesheet" href="css/variables.css">
        <link rel="stylesheet" href="css/general.css">
        <link rel="stylesheet" href="css/chrome.css">
        
        <link rel="stylesheet" href="css/print.css" media="print">
        

        <!-- Fonts -->
        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
        
        <link rel="stylesheet" href="fonts/fonts.css">
        

        <!-- Highlight.js Stylesheets -->
        <link rel="stylesheet" href="highlight.css">
        <link rel="stylesheet" href="tomorrow-night.css">
        <link rel="stylesheet" href="ayu-highlight.css">

        <!-- Custom theme stylesheets -->
        

        
    </head>
    <body>
        <!-- Provide site root to javascript -->
        <script type="text/javascript">
            var path_to_root = "";
            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
        </script>

        <!-- Work around some values being stored in localStorage wrapped in quotes -->
        <script type="text/javascript">
            try {
                var theme = localStorage.getItem('mdbook-theme');
                var sidebar = localStorage.getItem('mdbook-sidebar');

                if (theme.startsWith('"') && theme.endsWith('"')) {
                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                }

                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                }
            } catch (e) { }
        </script>

        <!-- Set the theme before any content is loaded, prevents flash -->
        <script type="text/javascript">
            var theme;
            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
            if (theme === null || theme === undefined) { theme = default_theme; }
            var html = document.querySelector('html');
            html.classList.remove('no-js')
            html.classList.remove('light')
            html.classList.add(theme);
            html.classList.add('js');
        </script>

        <!-- Hide / unhide sidebar before it is displayed -->
        <script type="text/javascript">
            var html = document.querySelector('html');
            var sidebar = 'hidden';
            if (document.body.clientWidth >= 1080) {
                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                sidebar = sidebar || 'visible';
            }
            html.classList.remove('sidebar-visible');
            html.classList.add("sidebar-" + sidebar);
        </script>

        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
            <div class="sidebar-scrollbox">
                <ol class="chapter"><li class="chapter-item expanded "><a href="what_is_it.html"><strong aria-hidden="true">1.</strong> What is Bracket-lib</a></li><li class="chapter-item expanded "><a href="linking.html"><strong aria-hidden="true">2.</strong> Quick Start</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="hello_terminal.html" class="active"><strong aria-hidden="true">2.1.</strong> Hello Terminal</a></li><li class="chapter-item expanded "><a href="individual_parts.html"><strong aria-hidden="true">2.2.</strong> Using Individual Components</a></li></ol></li><li class="chapter-item expanded "><a href="examples.html"><strong aria-hidden="true">3.</strong> Using the Examples</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="ex_color.html"><strong aria-hidden="true">3.1.</strong> Color Examples</a></li><li class="chapter-item expanded "><a href="ex_geometry.html"><strong aria-hidden="true">3.2.</strong> Geometry Examples</a></li><li class="chapter-item expanded "><a href="ex_noise.html"><strong aria-hidden="true">3.3.</strong> Noise Examples</a></li><li class="chapter-item expanded "><a href="ex_path.html"><strong aria-hidden="true">3.4.</strong> Pathfinding Examples</a></li><li class="chapter-item expanded "><a href="ex_rng.html"><strong aria-hidden="true">3.5.</strong> Random Examples</a></li><li class="chapter-item expanded "><a href="ex_bterm.html"><strong aria-hidden="true">3.6.</strong> Terminal Examples</a></li></ol></li><li class="chapter-item expanded "><a href="consoles.html"><strong aria-hidden="true">4.</strong> Working with Consoles</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="consoles_print.html"><strong aria-hidden="true">4.1.</strong> Printing to Consoles</a></li></ol></li></ol>
            </div>
            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
        </nav>

        <div id="page-wrapper" class="page-wrapper">

            <div class="page">
                
                <div id="menu-bar-hover-placeholder"></div>
                <div id="menu-bar" class="menu-bar sticky bordered">
                    <div class="left-buttons">
                        <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                            <i class="fa fa-bars"></i>
                        </button>
                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                            <i class="fa fa-paint-brush"></i>
                        </button>
                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                            <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                        </ul>
                        
                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                            <i class="fa fa-search"></i>
                        </button>
                        
                    </div>

                    <h1 class="menu-title">Bracket-Lib Usage Guide</h1>

                    <div class="right-buttons">
                        
                        <a href="print.html" title="Print this book" aria-label="Print this book">
                            <i id="print-button" class="fa fa-print"></i>
                        </a>
                        
                        
                    </div>
                </div>

                
                <div id="search-wrapper" class="hidden">
                    <form id="searchbar-outer" class="searchbar-outer">
                        <input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                    </form>
                    <div id="searchresults-outer" class="searchresults-outer hidden">
                        <div id="searchresults-header" class="searchresults-header"></div>
                        <ul id="searchresults">
                        </ul>
                    </div>
                </div>
                

                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                <script type="text/javascript">
                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                    });
                </script>

                <div id="content" class="content">
                    <main>
                        <h1><a class="header" href="#hello-terminal" id="hello-terminal">Hello Terminal</a></h1>
<p>You can get to <code>hello terminal</code> pretty quickly:</p>
<h2><a class="header" href="#create-a-new-project" id="create-a-new-project">Create a New Project</a></h2>
<p>Find the directory in which you want to start developing, and type <code>cargo init my_project</code> to create a new project.</p>
<h2><a class="header" href="#link-bracket-lib" id="link-bracket-lib">Link Bracket-Lib</a></h2>
<p>Open <code>Cargo.toml</code> in the newly created project, and expand the <code>[dependencies]</code> section as follows:</p>
<pre><code class="language-toml">[dependencies]
bracket-lib = &quot;0.8&quot;
</code></pre>
<h2><a class="header" href="#hello-minimal-terminal" id="hello-minimal-terminal">Hello Minimal Terminal</a></h2>
<p>The following code prints &quot;Hello Bracket World&quot; in a new simple console:</p>
<pre><pre class="playground"><code class="language-rust">use bracket_lib::prelude::*;

struct State {}

impl GameState for State {
    fn tick(&amp;mut self, ctx: &amp;mut BTerm) {
        ctx.print(1, 1, &quot;Hello Bracket World&quot;);
    }
}

fn main() -&gt; BError {
    let context = BTermBuilder::simple80x50()
        .with_title(&quot;Hello Minimal Bracket World&quot;)
        .build()?;

    let gs: State = State {};
    main_loop(context, gs)
}
</code></pre></pre>
<p>This provides what you need for a minimal start:</p>
<ol>
<li>Importing the <code>prelude</code> from <code>bracket_lib</code> makes the various types and functions available.</li>
<li>You have to create a <code>State</code> object. This is where your ongoing game state is stored.</li>
<li>Implementing <code>GameState</code> provides <code>bracket-lib</code> with a <code>tick</code> function to call on every frame.</li>
<li>Your <code>main</code> function constructs a terminal---in this case an 80x50 text console.</li>
<li>You create a <code>State</code> object, even though it doesn't have much state to store.</li>
<li>Launching <code>main_loop</code> hands control over to <code>bracket-lib</code>, and runs the <code>tick</code> function on every rendered frame.</li>
</ol>
<h2><a class="header" href="#bouncy-hello-world" id="bouncy-hello-world">Bouncy Hello World</a></h2>
<p>Another example (<code>hello_terminal</code> in the <code>bracket-lib</code> source) provides a bouncing &quot;Hello World&quot;. Let's use it to explore some of the features available in the library:</p>
<pre><pre class="playground"><code class="language-rust">use bracket_lib::prelude::*;

struct State {
    y: i32,
    going_down: bool,
}

impl GameState for State {
    fn tick(&amp;mut self, ctx: &amp;mut BTerm) {
        let col1 = RGB::named(CYAN);
        let col2 = RGB::named(YELLOW);
        let percent: f32 = self.y as f32 / 50.0;
        let fg = col1.lerp(col2, percent);

        ctx.cls();
        ctx.printer(
            40,
            49,
            &quot;#[blue]Hello #[pink]Bracket#[] world.&quot;,
            TextAlign::Center,
            Some(RGBA::from_u8(200, 200, 200, 255)),
        );

        ctx.print_color(
            1,
            self.y,
            fg,
            RGB::named(BLACK),
            &quot;♫ ♪ Hello Bracket World ☺&quot;,
        );

        if self.going_down {
            self.y += 1;
            if self.y &gt; 48 {
                self.going_down = false;
            }
        } else {
            self.y -= 1;
            if self.y &lt; 2 {
                self.going_down = true;
            }
        }

        ctx.draw_box(39, 0, 20, 3, RGB::named(WHITE), RGB::named(BLACK));
        ctx.printer(
            58,
            1,
            &amp;format!(&quot;#[pink]FPS: #[]{}&quot;, ctx.fps),
            TextAlign::Right,
            None,
        );
        ctx.printer(
            58,
            2,
            &amp;format!(&quot;#[pink]Frame Time: #[]{} ms&quot;, ctx.frame_time_ms),
            TextAlign::Right,
            None,
        );
    }
}

fn main() -&gt; BError {
    let context = BTermBuilder::simple80x50()
        .with_title(&quot;Hello Bracket World&quot;)
        .build()?;

    let gs: State = State {
        y: 1,
        going_down: true,
    };

    register_palette_color(&quot;blue&quot;, RGB::named(BLUE));
    register_palette_color(&quot;pink&quot;, RGB::named(MAGENTA));

    main_loop(context, gs)
}
</code></pre></pre>
<p>There's quite a lot to unwrap here, so let's go through a quick tour of using <code>bracket-lib</code>.</p>
<h3><a class="header" href="#the-state-structure" id="the-state-structure">The State Structure</a></h3>
<p>Everything your program needs to retain during execution lives in your state structure (well, you could use globals and lazy-statics). In this case, we're storing two variables in <code>State</code>:</p>
<ul>
<li><code>y</code> stores the current vertical location of the bouncing &quot;Hello Bracket World&quot;.</li>
<li><code>going_down</code> stores whether the words are going up or down at the moment. It changes direction at the top and bottom of the screen.</li>
</ul>
<h3><a class="header" href="#setup" id="setup">Setup</a></h3>
<p>In the <code>main</code> function, we start by initializing <code>bracket-terminal</code>. We ask for a simple 80x50 console, and title the window. The <code>build()</code> function actually creates the window; the other chained functions return an object <em>describing</em> what you want. There's a lot of options you can choose, documented elsewhere in this guide.</p>
<p>We initialize <code>State</code> with some starting values for the bouncing text. Then we call <code>register_palette_color</code>---more on that in &quot;pretty printing&quot;, below. Finally, we call <code>main_loop</code> to begin running the program---and calling <code>tick</code> every frame.</p>
<h3><a class="header" href="#printing-to-the-console" id="printing-to-the-console">Printing to the Console</a></h3>
<ol>
<li>The <code>tick</code> function starts by defining some colors. The <code>RGB::named(xxx)</code> functions return a color object. The library defines all of the W3C named colors; you can also use <code>from_rgb</code> to specify one yourself. These colors are then used in various printing functions.</li>
<li>Then it does a little dance to figure out where to draw the bouncing hello world.</li>
<li><code>ctx.cls()</code> clears the console.</li>
<li><code>ctx.printer</code> is then used to &quot;pretty print&quot; the words &quot;Hello Bracket World&quot;. 
<ol>
<li>The decorators <code>#[blue]</code>, <code>#[pink]</code> specify that text following that marker should be in the color that was registered wih the <code>register_palette_color</code> label.</li>
<li>The two numbers (40, 49) are screen coordinates.</li>
<li><code>TextAlign::center</code> will center the text horizontally around the specified coordinates.</li>
<li><code>Some(RGBA::from_u8(200, 200, 200, 255))</code> describes a background color for the text.</li>
</ol>
</li>
<li>Then we use the <code>print_color</code> commands, which is a simpler way to put single-color text on the console.</li>
<li>Some more <code>printer</code> calls, demonstrating different alignments and color settings.</li>
</ol>
<p>Notice that in the text, we use unicode. <code>♫ ♪ Hello Bracket World ☺</code> is valid, because the characters are part of the codepage-437 set---and <code>bracket-terminal</code> automatically translates them.</p>
<p>You'll find more detailed usage instructions throughout this document.</p>

                    </main>

                    <nav class="nav-wrapper" aria-label="Page navigation">
                        <!-- Mobile navigation buttons -->
                        
                            <a rel="prev" href="linking.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                <i class="fa fa-angle-left"></i>
                            </a>
                        

                        
                            <a rel="next" href="individual_parts.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                <i class="fa fa-angle-right"></i>
                            </a>
                        

                        <div style="clear: both"></div>
                    </nav>
                </div>
            </div>

            <nav class="nav-wide-wrapper" aria-label="Page navigation">
                
                    <a rel="prev" href="linking.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                        <i class="fa fa-angle-left"></i>
                    </a>
                

                
                    <a rel="next" href="individual_parts.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                        <i class="fa fa-angle-right"></i>
                    </a>
                
            </nav>

        </div>

        

        

        

        
        <script type="text/javascript">
            window.playground_copyable = true;
        </script>
        

        

        
        <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
        

        <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
        <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
        <script src="book.js" type="text/javascript" charset="utf-8"></script>

        <!-- Custom JS scripts -->
        

        

    </body>
</html>
